Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Browse events

This section covers the essential events supported by the browse, including:

Basic events — Occur when the user selects a row in the browse or scrolls through the data in the browse.
Row events — Occur when the user enters or leaves a particular browse row or when the browse displays data values in a row.
Column events — Occur when the user enters or leaves an enabled cell for a browse column.

Basic events

The basic browse events include:

VALUE-CHANGED — Occurs each time the user selects or deselects a row. Note that the event name is slightly misleading in that it is not meant to imply that the value of the data in the row has been modified, only that a different row has been selected.
HOME — Occurs when the user repositions the browse to the beginning of the query’s result set by pressing the HOME key.
END — Occurs when the user repositions the browse to the end of the query’s result set by pressing the END key.
OFF-END and OFF-HOME — Occur when the user uses the vertical scrollbar or arrow keys to scroll all the way to the end or the top of the browse.
DEFAULT-ACTION — Occurs when the user presses RETURN or ENTER or when the user double-click a row. DEFAULT-ACTION also has the side effect of selecting the row that is currently highlighted.
SCROLL-NOTIFY — Occurs when the user adjusts the scrollbar.

Typically, you use the VALUE-CHANGED and DEFAULT-ACTION events to link your browse to other parts of your application. Your current test window contains an example of the use of VALUE-CHANGED. Whenever the current row in the Order browse is changed, the VALUE-CHANGED event occurs and the trigger executes to retrieve its OrderLines and to display them in the second browse.

The DEFAULT-ACTION event occurs when the user explicitly selects a row not just by positioning to it, but by either double-clicking it or pressing ENTER.

To define a DEFAULT-ACTION trigger for the Order browse:

In the Section Editor, select the Triggers section and the OrderBrowse object.
Click the New button and select DEFAULT-ACTION from the list of browse events.
Enter this MESSAGE statement for the event:

DO:   MESSAGE "This Order's SalesRep is " Order.SalesRep SKIP           "and the terms are " Order.Terms VIEW-AS ALERT-BOX. END.

Run the window procedure and double-click on one of the Order rows to see the message:

The SCROLL-NOTIFY event is important if you plan to overlay other botches on browse cells, because it notifies you whenever the position of the rows of data within the browse viewport is changed by a scrolling action. SCROLL-NOTIFY gives you the ability to move the overlay widget to keep pace with the user’s scrolling. See the "Overlaying objects on browse cells" section for more information on this technique.

You could use the OFF-END or OFF-HOME event to retrieve more data to all the rows in the browse’s query, for example, when there are too many rows to retrieve at once. Note that if the user scrolls by clicking and holding the up or down arrows at the bottom and top of the vertical scrollbar, the OFF-HOME or OFF-END event does not occur until the user releases the mouse key.

Row events

The browse supports three row-specific events:

ROW-ENTRY — Occurs when a user enters edit mode on a selected row. This occurs when the user clicks on an enabled cell within a row.
ROW-LEAVE — Occurs when the user leaves edit mode. This occurs when the user leaves the enabled cells within a row, either by selecting a different row or selecting a nonenabled cell within the same row.
ROW-DISPLAY — Occurs when a row becomes visible in the browse viewport.

You can find examples of how ROW-ENTRY and ROW-LEAVE work in the sections on updating and creating browse rows later in the "Manipulating rows in the browse" section.

The ROW-DISPLAY event lets you change the color and font attributes of a row or individual cells or to reference field values in the row. The event also lets you change the format of a browse-cell by changing the value of its FORMAT attribute. You can also use the ROW-DISPLAY event to change the SCREEN-VALUE of one or more cells within the row.

For example, you can create a ROW-DISPLAY event for the OrderBrowse in your test window with this code:

DO:   Order.PO:SCREEN-VALUE IN BROWSE orderBrowse =       "PO" + STRING (Order.OrderNum).   IF Order.ShipDate = ? THEN       ShipDate:BGCOLOR IN BROWSE OrderBrowse = 12. END.

This changes the displayed value for the PO column and also checks the value of the ShipDate and changes its background color to signal that the ShipDate has not been entered, as shown in Figure 12–1.

Figure 12–1: Result of ROW-DISPLAY event example

Notes: If you want to use this technique to change the colors of an array extent field, you must do so by directly referencing each member.

In character interfaces, the DCOLOR attribute specifies the color of an individual cell.

Column events

There are LEAVE and ENTRY events that reference the browse object itself. For example:

On ENTRY OF OrderBrowse DO:    .    .    . END.

You can also write LEAVE and ENTRY triggers for individual columns. These triggers can refer to fields in the current row and can set and get attributes of the current cell by using either the name of the column in the browse or the SELF keyword. For example, you can enable the PO column in the OrderBrowse and then define this LEAVE trigger for it:

DO:   IF Order.PO:SCREEN-VALUE IN BROWSE OrderBrowse BEGINS "X" then      Order.PO:BGCOLOR IN BROWSE OrderBrowse = 12. /* RED */ END.

Or more simply, you can use the SELF keyword to refer to the cell:

DO:   IF SELF:SCREEN-VALUE BEGINS "X" then      SELF:BGCOLOR = 12. /* RED */ END.

Either way, you see the result shown in Figure 12–2 when you run the procedure.

Figure 12–2: Result of column event example

Searching columns

There are also two events that let you interact with search mode. START-SEARCH occurs when the user chooses a column label. END-SEARCH occurs when the user enters edit mode on a cell or selects a row. You can apply both of these events to columns to force the start and end of search mode.

When a read-only browse has focus, typing any printable key (an alphanumeric character) forces Progress to reposition the browse to the first row where the first character of the first browse column matches the typed character. Thus, the read-only browse allows searching, but based only on the data in the first column. If the browse finds no match, it wraps to the top of the column and continues searching.

In an updateable browse, the user can select the column that is to be the basis of the character search. First, the user clicks a column label. The column label depresses. When the user types any printable key, Progress searches for the first row in that column that matches and focuses that row. Column searches also wrap to the top if necessary.

Note: A column search on a browse associated with a query with the INDEXED-REPOSITION option does not wrap to the top of the column if it cannot find a record to satisfy the search. This behavior is a side effect of the reposition optimization. To work around this, you can apply HOME to the query before starting the search.

There are two ways to extend this basic behavior:

You can configure an updateable browse to look like a read-only browse. This technique gives you selectable columns and searching on those columns even when you don’t want to allow rows in the browse to be modified.
You can use the START-SEARCH and END-SEARCH browse events to trap the beginning and end of search mode and write to your own search routines.

As noted, the column-searching feature is exclusive to the updateable browse. The read-only browse can do one-character deep searches on the initial column of the browse. You can work around this by defining your browse with one field enabled for input and the NO-ROW-MARKERS option specified. After the definition, disable the enabled column by setting the column’s READ-ONLY attribute to false. This provides an updateable browse that looks like a read-only browse. The updateable browse retains the ability for the user to select individual columns and perform searches on them.

Note: The column searching capability is not available in character interfaces.